home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacApp Release 10 / MacApp Release 10 - HD Ready / Libraries / Framework / Includes / UDragDrop.h < prev    next >
Encoding:
Text File  |  1996-04-03  |  19.5 KB  |  639 lines  |  [TEXT/MPS ]

  1. //----------------------------------------------------------------------------------------
  2. // UDragDrop.h
  3. // Copyright © 1984-96 by Apple Computer, Inc. All rights reserved.
  4. //----------------------------------------------------------------------------------------
  5.  
  6. #if qDrag
  7.  
  8. #ifndef __UDRAGDROP__
  9. #define __UDRAGDROP__
  10.  
  11. // MacApp
  12.  
  13. #ifndef __UCOMMAND__
  14. #include "UCommand.h"
  15. #endif
  16.  
  17. #ifndef __ULIST__
  18. #include "UList.h"
  19. #endif
  20.  
  21. #ifndef __ULISTITERATOR__
  22. #include "UListIterator.h"
  23. #endif
  24.  
  25. #ifndef __UOBJECT__
  26. #include "UObject.h"
  27. #endif
  28.  
  29. #ifndef __USTREAM__
  30. #include "UStream.h"
  31. #endif
  32.  
  33. // Toolbox
  34.  
  35. #ifndef __DRAG__
  36. #include <Drag.h>
  37. #endif
  38.  
  39. //----------------------------------------------------------------------------------------
  40. // Forward and external class declarations. 
  41. //----------------------------------------------------------------------------------------
  42.  
  43. class CAEDesc;
  44. class TDragDropBehavior;
  45. class TDragItem;
  46. class TDragItemList;
  47. class TDragFlavorStream;
  48. class TScroller;
  49. class TToolboxEvent;
  50. class TView;
  51. class TWindow;
  52.  
  53. //----------------------------------------------------------------------------------------
  54. // Constants
  55. //----------------------------------------------------------------------------------------
  56.  
  57. const short kCanReceiveDrop = 0;
  58. const short kCantReceiveDrop = 1;
  59. const short kDropStatusUnknown = 2;
  60.  
  61. //----------------------------------------------------------------------------------------
  62. // CFlavorFlags is a toolbox compatible class for the drag manager FlavorFlags struct.
  63. // It is bitwise since it contains no virtual functions.
  64. //----------------------------------------------------------------------------------------
  65.  
  66. #if PRAGMA_ALIGN_SUPPORTED
  67. #pragma options align=mac68k
  68. #endif
  69.  
  70. struct CFlavorFlags
  71. {
  72.     FlavorFlags    fFlags;
  73.     
  74.     // Constructors
  75.     inline CFlavorFlags();
  76.     inline CFlavorFlags(const FlavorFlags flags);
  77.     
  78.     // Conversion operators
  79.     
  80.     inline operator FlavorFlags() const;
  81.     inline operator FlavorFlags*();
  82.     
  83.     // Accessors
  84.     
  85.     inline Boolean GetSenderOnly() const;
  86.     inline Boolean GetSenderTranslated() const;
  87.     inline Boolean GetNotSaved() const;
  88.     inline Boolean GetSystemTranslated() const;
  89.     
  90.     // Mutators
  91.     
  92.     inline void SetSenderOnly(const Boolean senderOnly);
  93.     inline void SetSenderTranslated(const Boolean senderTranslated);
  94.     inline void SetNotSaved(const Boolean notSaved);
  95.     inline void SetSystemTranslated(const Boolean systemTranslated);
  96. };
  97.     
  98. #if PRAGMA_ALIGN_SUPPORTED
  99. #pragma options align=reset
  100. #endif
  101.  
  102. //--------------------------------------------------------------------------------
  103. // Inline definitions for methods in CFlavorFlags
  104. //--------------------------------------------------------------------------------
  105.  
  106. inline CFlavorFlags::CFlavorFlags() : fFlags(0L) {};
  107.  
  108. inline CFlavorFlags::CFlavorFlags(const FlavorFlags flags) : fFlags(flags) {};
  109.  
  110. inline CFlavorFlags::operator FlavorFlags() const
  111. {
  112.     return fFlags;
  113. }
  114.  
  115. inline CFlavorFlags::operator FlavorFlags*()
  116. {
  117.     return &fFlags;
  118. }
  119.  
  120. inline Boolean CFlavorFlags::GetSenderOnly() const
  121. {
  122.     return fFlags & flavorSenderOnly;
  123. }
  124.  
  125. inline Boolean CFlavorFlags::GetSenderTranslated() const
  126. {
  127.     return (fFlags & flavorSenderTranslated) >> 1;
  128. }
  129.  
  130. inline Boolean CFlavorFlags::GetNotSaved() const
  131. {
  132.     return (fFlags & flavorNotSaved) >> 2;
  133. }
  134.  
  135. inline Boolean CFlavorFlags::GetSystemTranslated() const
  136. {
  137.     return (fFlags & flavorSystemTranslated) >> 8;
  138. }
  139.  
  140. inline void CFlavorFlags::SetSenderOnly(const Boolean senderOnly)
  141. {
  142.     if (senderOnly)
  143.         fFlags |= flavorSenderOnly;
  144.     else
  145.         fFlags &= ~flavorSenderOnly;
  146. }
  147.  
  148. inline void CFlavorFlags::SetSenderTranslated(const Boolean senderTranslated)
  149. {
  150.     if (senderTranslated)
  151.         fFlags |= flavorSenderTranslated;
  152.     else
  153.         fFlags &= ~flavorSenderTranslated;
  154. }
  155.  
  156. inline void CFlavorFlags::SetNotSaved(const Boolean notSaved)
  157. {
  158.     if (notSaved)
  159.         fFlags |= flavorNotSaved;
  160.     else    
  161.         fFlags &= ~flavorNotSaved;
  162. }
  163.  
  164. inline void CFlavorFlags::SetSystemTranslated(const Boolean systemTranslated)
  165. {
  166.     if (systemTranslated)
  167.         fFlags |= flavorSystemTranslated;
  168.     else
  169.         fFlags &= ~flavorSystemTranslated;
  170. }
  171.     
  172. //----------------------------------------------------------------------------------------
  173. // TDragDropSession: This type represents a drag and drop session.  It contains all the
  174. // data necessary to enable communication and negotiation between internal and external
  175. // draggers and drop sites.  MacApp supports drag and drop based on the Macintosh Drag
  176. // Manager.
  177. //----------------------------------------------------------------------------------------
  178.  
  179. class TDragDropSession : public TObject
  180. {
  181.     MA_DECLARE_CLASS;
  182.  
  183. public:
  184.     
  185.     static TDragDropSession* fgDragDropSession;    // global drag drop session
  186.     
  187. protected:
  188.  
  189.     TView*                fDropTarget;            // The view that would receive the drop if 
  190.                                                 // the mouse button were released, or NULL.
  191.                                             
  192.     TView*                fDragSource;            // The view currently dragging, or NULL
  193.     
  194.     TScroller*            fScroller;                // Scroller assocated with the source view
  195.     
  196.     TWindow*            fSourceWindow;            // Current source window or NULL
  197.     
  198.     TWindow*            fTargetWindow;            // Current target window or NULL.
  199.     
  200.     TDragItemList*        fDragItemList;            // List of items in the current drag
  201.                                                         
  202.     DragReference        fDragReference;            // Drag Manager reference to the current drag
  203.     
  204.     Boolean                fDragLeftSourceView;    // True if the drag has left the source view
  205.     
  206.     Boolean                fTargetIsHilited;        // True if the target has been hilited
  207.  
  208.     Boolean                fUserRequestedCopy;        // True if user overrode move by holding down
  209.                                                 // the option key at the start or end of a
  210.                                                 // drag
  211.                                             
  212.     static DragTrackingHandlerUPP    fDragTrackingHandlerUPP;    // UPPs for drag manager
  213.     static DragReceiveHandlerUPP    fDragReceiveHandlerUPP;        // callbacks
  214.     static DragSendDataUPP            fDragSendDataUPP;
  215.                                             
  216. public:
  217.  
  218.     //------------------------------------------------------------------------------------
  219.     // Initializer, I<Method> and Free.
  220.     //------------------------------------------------------------------------------------
  221.     
  222.     TDragDropSession();
  223.         // Constructor
  224.         
  225.     void IDragDropSession();
  226.         // Call IObject
  227.         
  228.     virtual ~TDragDropSession();
  229.         // Destructor
  230.  
  231.     //----------------------------------------------------------------------------------------
  232.     // Static Drag Manager Callback Glue
  233.     //----------------------------------------------------------------------------------------
  234.  
  235.     static pascal OSErr DragTrackingHandlerGlue(DragTrackingMessage     message,
  236.                                                 WindowRef                theWindowMgrWindow,
  237.                                                 void*                    handlerRefCon,
  238.                                                 DragReference            theDragRef);
  239.         
  240.         // Glue to gDragDropSession::DragTrackingHandler. Installed as the
  241.         // DragTrackingHandler with the Drag Manager.
  242.         
  243.     static pascal OSErr DragReceiveHandlerGlue(WindowRef        theWindowMgrWindow,
  244.                                                 void*            handlerRefCon,
  245.                                                 DragReference    theDragRef);
  246.         // Glue to gDragDropSession::DragReceiveHandler. Installed as the
  247.         // DragReceiveHandler with the Drag Manager.
  248.         
  249.     static pascal OSErr DragSendDataProcGlue(FlavorType        theType,
  250.                                             void*            dragSendDataRefCon,
  251.                                             ItemReference    theItemRef,
  252.                                             DragReference    theDragRef);
  253.         // Glue to gDragDropSession::DragSendDataProc. Installed as the
  254.         // DragSendDataProc with the Drag Managers.
  255.  
  256.         
  257.     //------------------------------------------------------------------------------------
  258.     // Drag Manager Callbacks : called by the static Drag Manager callbacks to
  259.     // support polymorphic descendants.
  260.     //------------------------------------------------------------------------------------
  261.     
  262.     virtual void DragTrackingHandler(DragTrackingMessage    message,
  263.                                     WindowRef                theWindowMgrWindow,
  264.                                     void*                    handlerRefCon,
  265.                                     DragReference            theDragRef);
  266.         // Called by DragReceiveHandlerGlue
  267.  
  268.     virtual OSErr DragReceiveHandler(WindowRef        theWindowMgrWindow,
  269.                                     void*            handlerRefCon,
  270.                                     DragReference    theDragRef);
  271.         // Called by DragReceiveHandlerGlue
  272.     
  273.     virtual void DragSendDataProc(FlavorType        theType,
  274.                                     void*            dragSendDataRefCon,
  275.                                     ItemReference    theItemRef,
  276.                                     DragReference    theDragRef);
  277.         // Called by DragSendDataProcGlue
  278.     
  279.     //------------------------------------------------------------------------------------
  280.     // Drag Manager message handlers : called by DragTrackingHandler in response the
  281.     // the various messages received from the Drag Manager.
  282.     //------------------------------------------------------------------------------------
  283.     
  284.     virtual void HandleEnterHandler();
  285.         // Handler for dragTrackingEnterHandler message
  286.         
  287.     virtual void HandleLeaveHandler();
  288.         // Handler for dragTrackingLeaveHandler message
  289.         
  290.     virtual void HandleEnterWindow(TWindow* targetWindow);
  291.         // Handler for dragTrackingEnterWindow message
  292.         
  293.     virtual void HandleLeaveWindow();
  294.         // Handler for dragTrackingLeaveWindow message
  295.         
  296.     virtual void HandleTrackInWindow();
  297.         // Handle for dragTrackingInWindow message
  298.     
  299.     virtual Boolean HandleAutoScroll();
  300.         // AutoScroll if appropriate
  301.     
  302.     virtual Boolean HandleDragToTrash();
  303.         // Handle user dragging into the Finder trash
  304.         
  305.     //------------------------------------------------------------------------------------
  306.     // Member Data Access / Utility Methods
  307.     //------------------------------------------------------------------------------------
  308.     
  309.     inline DragReference GetDragReference() const;
  310.         // Get the current drag reference
  311.     
  312.     inline TView* GetCurrentDragSource() const;
  313.         // Returns the current drag source view
  314.         
  315.     inline TView* GetCurrentDropTarget() const;
  316.         // Returns the current drop target
  317.         
  318.     void GetGlobalDragMouse(CPoint& mouse, CPoint& pinnedMouse);
  319.         // Get the current drag mouse and pinned mouse in global screen coordinates
  320.         
  321.     void SetGlobalPinnedDragMouse(CPoint& pinnedMouse);
  322.         // Set the current pinned mouse in global screen coordinates
  323.         
  324.     virtual void SetDropTarget(TView *newDropTarget);
  325.         // Establish a new drop target. Hilite the new target and unhilite the old
  326.         // target if necessary.
  327.         
  328.     Boolean HasDragLeftSenderWindow() const;
  329.         // Returns true if the drag has left the sender window.
  330.         
  331.     virtual void ShowDropTargetHilite();
  332.         // Manages hiliting when a drag enters a new target
  333.         
  334.     virtual void HideDropTargetHilite();
  335.         // Manages hiliting when a drag exits a target
  336.         
  337.     //------------------------------------------------------------------------------------
  338.     // TWindow Registry Interface : Methods called by TWindow objects to register and
  339.     // unregister themselves as potential drop sites.
  340.     //------------------------------------------------------------------------------------
  341.     
  342.     virtual void RegisterDroppableWindow(TWindow*    theWindow,
  343.                                         WindowRef    theWindowMgrWindow);
  344.         // Installs tracking and receive callbacks for theWindowMgrWindow, using
  345.         // the associated TWindow as the handlerRefCon.
  346.         
  347.     virtual void UnregisterDroppableWindow(WindowRef theWindowMgrWindow);
  348.         // Removes the tracking and receive callbacks associated with a window.
  349.  
  350.     //------------------------------------------------------------------------------------
  351.     // Drag Data Access : Methods to access data contained in a drag.
  352.     //------------------------------------------------------------------------------------
  353.     
  354.     virtual unsigned short GetItemCount();
  355.         // Get the number of items contained in the drag
  356.         
  357.     //------------------------------------------------------------------------------------
  358.     // Drag Initiation and Management
  359.     //------------------------------------------------------------------------------------
  360.     
  361.     virtual Boolean UserIsDragging(CPoint& initialMouse);
  362.         // return true if the user is dragging
  363.     
  364.     virtual Boolean UserRequestedCopy();
  365.         // return true if the user requested a copy
  366.         
  367.     virtual void ClearDrag();
  368.         
  369.     virtual void StartDrag(TView* sourceView, TToolboxEvent* event, RgnHandle dragRegion);
  370.         // called by a view to initiate a drag operation
  371.         
  372.     virtual TDragItem* AddDragItem(ItemReference itemReference);
  373.         // called by a view to add an item to the current drag operation.
  374.         // A pointer to the item that was added is returned. The caller should NOT
  375.         // dispose the returned drag item.
  376.         
  377.     virtual TDragItem* GetDragItemByIndex(unsigned short index);
  378.         // Request an item from the current drag by its index. The caller should
  379.         // NOT dispose the returned drag item.
  380.         
  381.     virtual TDragItem* GetDragItemByReference(ItemReference itemReference);
  382.         // Request an item from the current drag by its index. The caller should
  383.         // NOT dispose the returned drag item.
  384.     
  385.     void GetDropLocationDescriptor(CAEDesc& dropLocationDesc) const;
  386.         // Get and AEDesc record describing the drop location
  387.     
  388.     Boolean    IsDropLocationFinderTrash() const;
  389.         // Return true if the drop location is the Finder trash
  390. }; // class TDragDropSession
  391.  
  392. //----------------------------------------------------------------------------------------
  393. // TDragDropSession inline methods
  394. //----------------------------------------------------------------------------------------
  395.  
  396. inline DragReference TDragDropSession::GetDragReference() const
  397. {
  398.     return fDragReference;
  399. } // TDragDropSession::GetDragReference
  400.  
  401. inline TView* TDragDropSession::GetCurrentDragSource() const
  402. {
  403.     return fDragSource;
  404. } // TDragDropSession::GetCurrentDragSource
  405.  
  406. inline TView* TDragDropSession::GetCurrentDropTarget() const
  407. {
  408.     return fDropTarget;
  409. } // TDragDropSession::GetCurrentDropTarget
  410.  
  411.  
  412. //----------------------------------------------------------------------------------------
  413. // TDragItemList
  414. //----------------------------------------------------------------------------------------
  415.  
  416. class TDragItemList : public TList
  417. {
  418.     MA_DECLARE_CLASS;
  419.     
  420. public:
  421.     
  422.     TDragItemList();
  423.     
  424.     virtual ~TDragItemList();
  425.     
  426.     void IDragItemList();
  427.     
  428.     void BuildListFromDrag();
  429. };
  430.  
  431. //----------------------------------------------------------------------------------------
  432. // TDragItem
  433. //----------------------------------------------------------------------------------------
  434.  
  435. class TDragItem : public TObject
  436. {
  437.     MA_DECLARE_CLASS;
  438.  
  439. protected:
  440.         
  441.     ItemReference        fItemReference;
  442.         
  443.     FlavorType            fFlavorType;
  444.     
  445.     long                fFlavorOffset;
  446.         
  447. public:
  448.     
  449.     TDragItem();
  450.     
  451.     TDragItem(ItemReference    itemReference);
  452.     
  453.     ~TDragItem();
  454.     
  455.     void IDragItem();
  456.         
  457.     inline ItemReference GetItemReference();
  458.         // Returns this items reference constant
  459.         
  460.     void AddFlavor(    FlavorType         newFlavor, 
  461.                     CFlavorFlags&     flavorFlags,
  462.                     void*            buffer,
  463.                     long            count);
  464.         // Adds a new flavor to this item. Focuses on the flavor and writes
  465.         // count bytes from the buffer into the new flavor
  466.         
  467.     void PromiseFlavor(FlavorType newFlavor, CFlavorFlags& flavorFlags);
  468.         // Add a new flavor to the item as a promise.  Focus on the promised
  469.         // flavor. If data is written to the promised flavor before the drag
  470.         // actually begins, the promise will be negated and it will be assumed
  471.         // that all flavor data has been provided
  472.         
  473.     unsigned short CountFlavors();
  474.         // Returns the number of flavors in this drag item
  475.         
  476.     Boolean FlavorExists(FlavorType    requestedFlavor);
  477.         // Returns true if a flavor of the given flavor type exists
  478.  
  479.     void FocusOnFlavor(FlavorType focusFlavor);
  480.         // Focuses on the given flavor type
  481.     
  482.     long GetPosition();
  483.         // Returns the current position of the focused flavor
  484.         
  485.     void SetPosition(long newPosition);
  486.         // Sets the current position of the focused flavor
  487.         
  488.     CRect GetBounds();
  489.         // Get the bounding rectangle of the item in global coordinates.
  490.         
  491.     void SetBounds(CRect& itemBounds);
  492.         // Optionally set the bounding rectangle of the item.  If a rectangle
  493.         // is not specified, bounds will be represented as an empty rectangle
  494.         // centered under the pinned mouse location.
  495.         
  496.     long GetSize();
  497.         // Returns the size of the currently focused flavor. This method forces promises
  498.         // to be fulfilled. If a translation is necessary to provide the focused data,
  499.         // the translation will happen. Be aware that this call may be slow and expensive
  500.         
  501.     CFlavorFlags GetFlags();
  502.         // Returns the flavor flags of the currently focused flavor
  503.         
  504.     FlavorType GetFlavorType();
  505.         // Returns the type of the currently focused flavor
  506.         
  507.     void GetData(void *buffer, long& count);
  508.         // Reads count bytes from the currently focused flavor at the current offset
  509.         // into the buffer
  510.         
  511.     Handle GetDataAsHandle();
  512.         // Creates and returns a permanent handle that contains the data in the
  513.         // focused flavor after the current offset
  514.         
  515.     void SetData(void *buffer, long count);
  516.         // Writes count bytes to the currently focused flavor at the current offset
  517.         // from the buffer
  518.         
  519.     void SetDataFromHandle(Handle dataHandle);
  520.         // Writes the data in dataHandle out to the focused flavor beginning
  521.         // at the current offset
  522.         
  523.     TDragFlavorStream* GetDataStream();
  524.         // Get a MacApp stream that can be used to read or write flavor data to the
  525.         // currently focused flavor. It is the callers responsibility to dispose
  526.         // the stream.
  527. };
  528.  
  529. //----------------------------------------------------------------------------------------
  530. // TDragItem Inline Methods
  531. //----------------------------------------------------------------------------------------
  532.  
  533. inline ItemReference TDragItem::GetItemReference()
  534. {
  535.     return fItemReference;
  536. } // TDragItem::GetItemReference
  537.     
  538. //----------------------------------------------------------------------------------------
  539. // TDragFlavorStream : stream class used to access flavor data supplied by the Drag
  540. // Manager.
  541. //
  542. // NOTE: Flavor streams are valid ONLY immediately following a drag operation. When
  543. // a drop is received, all necessary data should be extracted from any flavor streams
  544. // that are created before control is returned to the drag manager.  Building in debug
  545. // mode turns on a instance counter for TDragFlavorStreams.  If control is returned
  546. // to the drag manager before all TDragFlavorStreams are disposed, a ProgramBreak
  547. // occurs.
  548. //----------------------------------------------------------------------------------------
  549.  
  550. class TDragFlavorStream : public TStream
  551. {
  552.     MA_DECLARE_CLASS;
  553.  
  554. protected:
  555.     
  556.     ItemReference    fItemReference;
  557.     
  558.     FlavorType        fFlavorType;
  559.  
  560.     long             fPosition;    // offset into stream
  561.     
  562. #if qDebug
  563.     static short    fInstanceCount;    // count instances of this class in debug mode
  564. #endif // qDebug
  565.     
  566. public:
  567.     TDragFlavorStream();
  568.     
  569.     virtual ~TDragFlavorStream();
  570.     
  571.     void IDragFlavorStream(ItemReference theReference, FlavorType theFlavor);
  572.     
  573. #if qDebug    
  574.     static void CheckInstanceCount();
  575. #endif // qDebug 
  576.     
  577.     //------------------------------------------------------------------------------------
  578.     // Access:  
  579.     //------------------------------------------------------------------------------------
  580.  
  581.     virtual long GetPosition();
  582.     
  583.     virtual void SetPosition(long newPosition);
  584.         
  585.     virtual long GetSize();
  586.         
  587.     virtual void ReadBytes(void* p, long count);
  588.     
  589.     virtual void WriteBytes(const void* p, long count);
  590.     
  591. }; // class TDragFlavorStream
  592.  
  593. //----------------------------------------------------------------------------------------
  594. // CDragItemIterator
  595. //----------------------------------------------------------------------------------------
  596.  
  597. class CDragItemIterator : public CArrayIterator
  598. {
  599.   public:
  600.     CDragItemIterator(TDragItemList *itsDragItemList, Boolean itsForward = kIterateForward);
  601.         // Constructor
  602.     
  603.     virtual ~CDragItemIterator();
  604.         // Destructor
  605.     
  606.     TDragItem* CurrentDragItem();
  607.     
  608.     TDragItem* FirstDragItem();
  609.     
  610.     TDragItem* NextDragItem();
  611. };
  612.  
  613. //----------------------------------------------------------------------------------------
  614. // TInvalCursorCommand
  615. //----------------------------------------------------------------------------------------
  616.  
  617. class TInvalCursorCommand : public TCommand
  618. {
  619.     MA_DECLARE_CLASS;
  620.  
  621. public:
  622.  
  623.     TInvalCursorCommand();
  624.     
  625.     void IInvalCursorCommand();
  626.     
  627.     virtual void DoIt();
  628. };
  629. //----------------------------------------------------------------------------------------
  630. // Globals defined by this unit
  631. //----------------------------------------------------------------------------------------
  632.  
  633. void InitUDragManager();
  634. void InitializeResidentDragSegment();
  635.  
  636. #endif // qDrag
  637.  
  638. #endif  // __UDRAGDROP__
  639.